/**
 * \addtogroup Led LED API
 * @{
 * This file specifies the Samsung LED API for Windows Mobile Devices.
 *
 * A typical Samsung device contains two LEDs: a notification LED and 
 * a keyboard LED, both of which can be controlled with the LED API. (There is 
 * also an LCD display backlight, which is controlled by the settings interface 
 * and not the SMI LED API.)
 *
 * The LED API controls two LED attributes:
 *  - Display State - The keyboard LED can be either on or off; the notification
 *                    LED can be on, off, or blinking. 
 *  - Color - The notification LED can display different colors, depending on 
 *            the hardware setting. The Keyboard LED is monochrome white.
 *
 * Copyright &copy; 2009 Samsung Electronics
 * 
 * File: smiLed.h
 */


#ifndef _SMI_LED_H_
#define _SMI_LED_H_ 


#include <smiSDK.h>

#define SMI_LED_RED     0x000000FF
#define SMI_LED_GREEN   0x0000FF00
#define SMI_LED_YELLOW  0x0000FFFF
#define SMI_LED_BLUE    0x00FF0000
#define SMI_LED_MAGENTA 0x00FF00FF
#define SMI_LED_CYAN    0x00FFFF00
#define SMI_LED_WHITE   0x00FFFFFF


/**
 * The ID for the notification LED.
 */
#define SMI_LED_ID_NOTIFICATION     0

/**
 * The ID for the keypad LED.
 */
#define SMI_LED_ID_KEYPAD           1

/**
 * Infinitely long duration.
 */
#define SMI_LED_INFINITE_DURATION 0xFFFFFFFF


/**
 *  LED error codes.
 */
typedef enum 
{
    SMI_LED_ERROR_COLOR_UNSUPPORTED   =  SMI_LED_RESULT_BASE 
} SmiLedError;


/**
 *  LED lighting patterns.
 */
typedef enum
{
	SMI_LED_PATTERN_SOLID     ,
	SMI_LED_PATTERN_BLINKING  
} SmiLedPattern;


/**
 * The LED's RGB color. The Microsoft-defined type COLORREF is used. When specifying an explicit 
 * RGB color, the COLORREF value has a hexadecimal format, such as 0x00bbggrr.
 */
typedef COLORREF SmiLedColor;

/**
 * Describes the light pattern of an LED. 
 */
typedef struct
{
	/**
	 * Indicates light pattern. 
	 */
    SmiLedPattern pattern;

	
	/**
	 * The amount of time an LED is on in a single cycle, in milliseconds. 
	 */
	UINT onTime;

	/**
	 * The amount of time an LED is off in a single cycle, in milliseconds. 
	 */
	UINT offTime;

	/**
	 * The total play time for the LED, in milliseconds. The LED cycle (which is the on time 
	 * plus the off time, in milliseconds) will be repeated for the duration. 
	 * SMI_LED_INFINITE_DURATION indicates an infinitely long LED on duration. 
	 * In the case that on time plus off time is set greater than the duration, 
	 * the duration is changed to the sum of the on time and off time.
	 */
	UINT duration;

	/**
	 * The LED's color. The accuracy of the display of a color is dependent on the color 
	 * intensity.  For example, with a color intensity of 1, any value from 0x000000 to 0x00007F 
	 * is no color; any value from 0x000080 to SMI_LED_RED (0x0000FF) is a red color.
	 */
	SmiLedColor color;
} SmiLedAttributes;

/**
 * The capabilities of the LED.
 */
struct SmiLedCapabilities
{
	/**
	 * LED blink support. Supports blink if value is 1, otherwise is 0.
	 */
	BOOL blinkIsSupported;
	
	/** 
	 * Indicates the supported color intensity on the LED. 
	 * 
	 * A colorIntensity value of 1 means R, G, B can each be either 
	 * 0 or 1, yielding a total of 8 colors when used in combination.
	 * A color intensity value of 3 means R, G, B can each be either
	 * 0, 1, 2, or 3, yielding a total of 64 colors.
	 */
	UINT colorIntensity;

	/**
	 * The value indicates the maximum on time value allowed, or 0 if it is not 
	 * adjustable.
	 */
	UINT maxOnTime;

	/**
	 * The value indicates the maximum off time value allowed, or 0 if it is not 
	 * adjustable.
	 */
	UINT maxOffTime;

	/**
 	 * The value indicates the maximum duration allowed, or 0 if it is 
	 * not adjustable.
	 */
	UINT maxDuration;
};

/**
 *  Gets the LED's capabilities information.
 *
 *  @param id [in]				The LED that will have its capabilities returned. 
 *  @param capabilities [out]	A pointer to the LED capability info.
 *
 *  @return 
 *								SMI_SUCCESS on success
 * \n							SMI_ERROR_INVALID_PARAMETER if the capabilities parameter is NULL
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if an LED with that id is not supported by the SDK
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */
SMI_API SMI_RESULT SmiLedGetCapabilities(UINT id, SmiLedCapabilities* capabilities);


/**
 *  Turns on an LED.
 *
 *  Only notification LEDs support multiple colors.
 *
 *  @param id [in]				The particular LED to be turned on.
 *  @param attributes [in]		The attributes of the designated LED device. 
 *
 *  @return 
 *								SMI_SUCCESS on success
 * \n							SMI_ERROR_INVALID_PARAMETER if one or more parameters is invalid
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if an LED with that id is not supported by the SDK
 * \n							SMI_LED_ERROR_COLOR_UNSUPPORTED if the color is not supported (used for notification LED only)
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */
SMI_API SMI_RESULT SmiLedTurnOn( UINT id, const SmiLedAttributes* attributes ); 


/**
 *  Turns off an LED. 
 *
 *  @param id [in]				The particular LED to be turned off.
 *
 *  @return 
 *								SMI_SUCCESS on success
 * \n							SMI_ERROR_INVALID_PARAMETER if the id parameter is invalid
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if an LED with that id is not supported by the SDK
 */
SMI_API SMI_RESULT SmiLedTurnOff(UINT id);


/**
 *  Gets the number of available LEDs.
 *
 *  @param ledCount [out]		The number of LEDs.
 *
 *  @return 
 *								SMI_SUCCESS on success
 * \n							SMI_ERROR_INVALID_PARAMETER if the input parameter is NULL
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if LEDs are not supported by the SDK on this phone model
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */
SMI_API SMI_RESULT SmiLedGetCount( UINT* ledCount );


#endif // define _SMI_LED_H_ 
/* @} */